Central Event System (Plug-ins)

Writing A Plug-in Event Handler

For a detailed example of writing a plug-in, please see the Site Map Plug-in example. The essential aspects are;

The Plug-in Assembly

You create a DLL which contains the class "Keyoti.SearchEngine.ExternalEventHandler" and any additional classes required to perform the custom tasks. It can reference whatever other assemblies are necessary.

Class Structure

The class (ExternalEventHandler) can be written in any .NET language, but must adhere to the following requirements;

Namespace: Class must be in Keyoti.SearchEngine
Class name: ExternalEventHandler
Constructor: Must take parameters of type IEventDispatcher, and Configuration
Methods: at least 1 method called DetachHandlers with no parameters.

Following these requirements allows the search engine to use the class. The constructor should attach handlers to the events from IEventDispatcher and the DetachHandlers should detach the handlers (this is called when the EventHandlerAssemblyPath property changes).

Example

Assign Location And Content Categories

Using A Plug-in

Configuration Settings

Once you have created your assembly, you will need to setup your Search application to communicate with the new logic. To do this, set the EventHandlerAssemblyPath property in the configuration settings, to the path of your project's output DLL (the path can be either, absolute or relative to the Index Directory). The configuration file can be edited by either;

Visual Studio: Right click on the SearchResult control, select Configuration.
Search Admin App: Select Manage Configuration from the main window.
Programmatically: Set the Configuration. EventHandlerAssemblyPath property.
Other: The configuration.xml file can be edited directly, this is located within your Index Directory folder.

Plug-in Location & References

Any assemblies which are referenced by the plug-in assembly will need to either be in the same folder or in the GAC (the search assemblies are installed in the GAC). It is suggested that the after development, the plug-in DLL is stored in location under the Index Directory - because the Index Directory is a portable unit, locating the plug-in under it will ensure they are not separated. The EventHandlerAssemblyPath can be set relative to the Index Directory.

Log Files

To check your extension plug-in is working as expected you can view the log file CentralEventDispatcher.txt under your Index Directory, which will be updated as soon as anything is attempted using the configuration (eg. edit settings, start a tool). You will need to ensure Logging has been enabled in the configuration settings before using your plug-in.

Example of successful entry;
08/14/2008 10:51 Success, initialized external event handler assembly @ C:\Inetpub\wwwroot\Search_Extension_Plugin\bin\SearchExtensionPlugin.dll

Notes

CAS (security permission) issues:

If accessing an external assembly (ie. CustomDataSetProvider or ExternalEventHandler) in anything below Full Trust, the external assembly must be located under the application directory.

External Assembly Location Tip:

When working with a plug-in DLL and the Admin Web App., place the plug-in DLL in the application BIN directory. This will make the DLL automatically updatable, without stopping the IIS service or killing the ASP.NET worker process.
If the plug-in is outside the application and it's subdirectories, ensure the ASPNET (IIS 5) or NetworkService (IIS 6) user can access the DLL, eg. run from command prompt

cacls "path to plug-in DLL" /E /G ASPNET:R

References To Search DLLs:

It is fine to reference the search DLLs, but attention must be paid to;